/*
 * 	<pre>
 *	EasyPeas.
 *  Copyright (C) 2007 S Owen
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License as published by the Free Software Foundation; either
 *  version 2.1 of the License, or (at your option) any later version.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 * 
 * Jul 24, 2007
 * Action.java
 * </pre>
 */
package org.easypeas.annotations;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * <p>
 * Signifies a method that performs an action on a POST.<br>
 * A forward can be defined mapped to a result of that action, defined by the
 * attribute <em>forwards</em> which is a list of Strings.Each element
 * represents a key mapped to a path, e.g <code>"success=/jackpot/win.vm"</code>
 * which may be a direct template or a path to be processed by the dispatcher.<br>
 * The String returned from the method maps to the key of the defined forward.<br>
 * The forward itself must start from just after the URL context, e.g.
 * http://localhost:9090/easypeas/math/result => /math/result<br>
 * <p>
 * <code>
 * &#064Action(name="add", forwards={"success=/math/add_result","failure=/error.vm"}<br>
 * public String add(HttpServletRequest req, HttpServletResponse res,Map<String, Object> map)...
 * <code><br>
 * A method can act as both a View and an Action, but it must differentiate within the method, 
 * and if it is an Action it must return a String.
 * </p>
 * <p>
 * The <em>name</em> attribute is mandatory.
 * </p>
 * @author S Owen
 *
 */
@Retention(value = RetentionPolicy.RUNTIME)
@Target(value = ElementType.METHOD)
public @interface Action {

	/**
	 * The name of the action, which is unique for all HTTP POST requests
	 * forwarded to this EasyPea. The name maps to the part of the URL path
	 * after the EasyPea name, or an EasyPea returned from an accessor;<br>
	 * e.g. POST /books/best/delete => invokes the action delete on the EasyPea
	 * returned by the accessor on the EasyPea books.
	 */
	String name();

	/**
	 * A method annotated with Action will return a String which indicates the
	 * flow from this action. This could indicate a state such as success or
	 * failure.<br>
	 * The forwards attribute provides the mapping of where to go next depending
	 * on this return value.<br>
	 * This attribute is assigned a list of '=' delimited key=value mappings,<br>
	 * see full {@link Action} description for more details.
	 */
	String[] forwards() default {};
}
